   Edition History:

   GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
Reference Manual (for 19.15 and 20.1, 20.2) v3.2, April, May 1997

   Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
Foundation, Inc.  Copyright (C) 1994, 1995 Sun Microsystems, Inc.
Copyright (C) 1995, 1996 Ben Wing.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Foundation.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided also
that the section entitled "GNU General Public License" is included
exactly as in the original, and provided that the entire resulting
derived work is distributed under the terms of a permission notice
identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that the section entitled "GNU General Public License"
may be included in a translation approved by the Free Software
Foundation instead of in the original English.

Process Filter Functions
------------------------

   A process "filter function" is a function that receives the standard
output from the associated process.  If a process has a filter, then
*all* output from that process is passed to the filter.  The process
buffer is used directly for output from the process only when there is
no filter.

   A filter function must accept two arguments: the associated process
and a string, which is the output.  The function is then free to do
whatever it chooses with the output.

   A filter function runs only while XEmacs is waiting (e.g., for
terminal input, or for time to elapse, or for process output).  This
avoids the timing errors that could result from running filters at
random places in the middle of other Lisp programs.  You may explicitly
cause Emacs to wait, so that filter functions will run, by calling
`sit-for' or `sleep-for' (see Waiting.), or `accept-process-output'
(see Accepting Output.).  Emacs is also waiting when the command
loop is reading input.

   Quitting is normally inhibited within a filter function--otherwise,
the effect of typing `C-g' at command level or to quit a user command
would be unpredictable.  If you want to permit quitting inside a filter
function, bind `inhibit-quit' to `nil'.  See Quitting.

   If an error happens during execution of a filter function, it is
caught automatically, so that it doesn't stop the execution of whatever
program was running when the filter function was started.  However, if
`debug-on-error' is non-`nil', the error-catching is turned off.  This
makes it possible to use the Lisp debugger to debug the filter
function.  See Debugger.

   Many filter functions sometimes or always insert the text in the
process's buffer, mimicking the actions of XEmacs when there is no
filter.  Such filter functions need to use `set-buffer' in order to be
sure to insert in that buffer.  To avoid setting the current buffer
semipermanently, these filter functions must use `unwind-protect' to
make sure to restore the previous current buffer.  They should also
update the process marker, and in some cases update the value of point.
Here is how to do these things:

     (defun ordinary-insertion-filter (proc string)
       (let ((old-buffer (current-buffer)))
         (unwind-protect
             (let (moving)
               (set-buffer (process-buffer proc))
               (setq moving (= (point) (process-mark proc)))

     (save-excursion
                 ;; Insert the text, moving the process-marker.
                 (goto-char (process-mark proc))
                 (insert string)
                 (set-marker (process-mark proc) (point)))
               (if moving (goto-char (process-mark proc))))
           (set-buffer old-buffer))))

The reason to use an explicit `unwind-protect' rather than letting
`save-excursion' restore the current buffer is so as to preserve the
change in point made by `goto-char'.

   To make the filter force the process buffer to be visible whenever
new text arrives, insert the following line just before the
`unwind-protect':

     (display-buffer (process-buffer proc))

   To force point to move to the end of the new output no matter where
it was previously, eliminate the variable `moving' and call `goto-char'
unconditionally.

   In earlier Emacs versions, every filter function that did regexp
searching or matching had to explicitly save and restore the match data.
Now Emacs does this automatically; filter functions never need to do it
explicitly.  See Match Data.

   A filter function that writes the output into the buffer of the
process should check whether the buffer is still alive.  If it tries to
insert into a dead buffer, it will get an error.  If the buffer is dead,
`(buffer-name (process-buffer PROCESS))' returns `nil'.

   The output to the function may come in chunks of any size.  A program
that produces the same output twice in a row may send it as one batch
of 200 characters one time, and five batches of 40 characters the next.

 - Function: set-process-filter PROCESS FILTER
     This function gives PROCESS the filter function FILTER.  If FILTER
     is `nil', then the process will have no filter.  If FILTER is `t',
     then no output from the process will be accepted until the filter
     is changed. (Output received during this time is not discarded,
     but is queued, and will be processed as soon as the filter is
     changed.)

 - Function: process-filter PROCESS
     This function returns the filter function of PROCESS, or `nil' if
     it has none.  `t' means that output processing has been stopped.

   Here is an example of use of a filter function:

     (defun keep-output (process output)
        (setq kept (cons output kept)))
          => keep-output

     (setq kept nil)
          => nil

     (set-process-filter (get-process "shell") 'keep-output)
          => keep-output

     (process-send-string "shell" "ls ~/other\n")
          => nil
     kept
          => ("lewis@slug[8] % "

     "FINAL-W87-SHORT.MSS    backup.otl              kolstad.mss~
     address.txt             backup.psf              kolstad.psf
     backup.bib~             david.mss               resume-Dec-86.mss~
     backup.err              david.psf               resume-Dec.psf
     backup.mss              dland                   syllabus.mss
     "
     "#backups.mss#          backup.mss~             kolstad.mss
     ")

Accepting Output from Processes
-------------------------------

   Output from asynchronous subprocesses normally arrives only while
XEmacs is waiting for some sort of external event, such as elapsed time
or terminal input.  Occasionally it is useful in a Lisp program to
explicitly permit output to arrive at a specific point, or even to wait
until output arrives from a process.

 - Function: accept-process-output &optional PROCESS SECONDS MILLISEC
     This function allows XEmacs to read pending output from processes.
     The output is inserted in the associated buffers or given to
     their filter functions.  If PROCESS is non-`nil' then this
     function does not return until some output has been received from
     PROCESS.

     The arguments SECONDS and MILLISEC let you specify timeout
     periods.  The former specifies a period measured in seconds and the
     latter specifies one measured in milliseconds.  The two time
     periods thus specified are added together, and
     `accept-process-output' returns after that much time whether or
     not there has been any subprocess output.  Note that SECONDS is
     allowed to be a floating-point number; thus, there is no need to
     ever use MILLISEC. (It is retained for compatibility purposes.)

     The function `accept-process-output' returns non-`nil' if it did
     get some output, or `nil' if the timeout expired before output
     arrived.

Sentinels: Detecting Process Status Changes
===========================================

   A "process sentinel" is a function that is called whenever the
associated process changes status for any reason, including signals
(whether sent by XEmacs or caused by the process's own actions) that
terminate, stop, or continue the process.  The process sentinel is also
called if the process exits.  The sentinel receives two arguments: the
process for which the event occurred, and a string describing the type
of event.

   The string describing the event looks like one of the following:

   * `"finished\n"'.

   * `"exited abnormally with code EXITCODE\n"'.

   * `"NAME-OF-SIGNAL\n"'.

   * `"NAME-OF-SIGNAL (core dumped)\n"'.

   A sentinel runs only while XEmacs is waiting (e.g., for terminal
input, or for time to elapse, or for process output).  This avoids the
timing errors that could result from running them at random places in
the middle of other Lisp programs.  A program can wait, so that
sentinels will run, by calling `sit-for' or `sleep-for' (see
Waiting.), or `accept-process-output' (see Accepting Output.).
Emacs is also waiting when the command loop is reading input.

   Quitting is normally inhibited within a sentinel--otherwise, the
effect of typing `C-g' at command level or to quit a user command would
be unpredictable.  If you want to permit quitting inside a sentinel,
bind `inhibit-quit' to `nil'.  See Quitting.

   A sentinel that writes the output into the buffer of the process
should check whether the buffer is still alive.  If it tries to insert
into a dead buffer, it will get an error.  If the buffer is dead,
`(buffer-name (process-buffer PROCESS))' returns `nil'.

   If an error happens during execution of a sentinel, it is caught
automatically, so that it doesn't stop the execution of whatever
programs was running when the sentinel was started.  However, if
`debug-on-error' is non-`nil', the error-catching is turned off.  This
makes it possible to use the Lisp debugger to debug the sentinel.
See Debugger.

   In earlier Emacs versions, every sentinel that did regexp searching
or matching had to explicitly save and restore the match data.  Now
Emacs does this automatically; sentinels never need to do it explicitly.
See Match Data.

 - Function: set-process-sentinel PROCESS SENTINEL
     This function associates SENTINEL with PROCESS.  If SENTINEL is
     `nil', then the process will have no sentinel.  The default
     behavior when there is no sentinel is to insert a message in the
     process's buffer when the process status changes.

          (defun msg-me (process event)
             (princ
               (format "Process: %s had the event `%s'" process event)))
          (set-process-sentinel (get-process "shell") 'msg-me)
               => msg-me

          (kill-process (get-process "shell"))
               -| Process: #<process shell> had the event `killed'
               => #<process shell>

 - Function: process-sentinel PROCESS
     This function returns the sentinel of PROCESS, or `nil' if it has
     none.

 - Function: waiting-for-user-input-p
     While a sentinel or filter function is running, this function
     returns non-`nil' if XEmacs was waiting for keyboard input from
     the user at the time the sentinel or filter function was called,
     `nil' if it was not.

Process Window Size
===================

 - Function: set-process-window-size PROCESS HEIGHT WIDTH
     This function tells PROCESS that its logical window size is HEIGHT
     by WIDTH characters.  This is principally useful with pty's.

Transaction Queues
==================

   You can use a "transaction queue" for more convenient communication
with subprocesses using transactions.  First use `tq-create' to create
a transaction queue communicating with a specified process.  Then you
can call `tq-enqueue' to send a transaction.

 - Function: tq-create PROCESS
     This function creates and returns a transaction queue
     communicating with PROCESS.  The argument PROCESS should be a
     subprocess capable of sending and receiving streams of bytes.  It
     may be a child process, or it may be a TCP connection to a server,
     possibly on another machine.

 - Function: tq-enqueue QUEUE QUESTION REGEXP CLOSURE FN
     This function sends a transaction to queue QUEUE.  Specifying the
     queue has the effect of specifying the subprocess to talk to.

     The argument QUESTION is the outgoing message that starts the
     transaction.  The argument FN is the function to call when the
     corresponding answer comes back; it is called with two arguments:
     CLOSURE, and the answer received.

     The argument REGEXP is a regular expression that should match the
     entire answer, but nothing less; that's how `tq-enqueue' determines
     where the answer ends.

     The return value of `tq-enqueue' itself is not meaningful.

 - Function: tq-close QUEUE
     Shut down transaction queue QUEUE, waiting for all pending
     transactions to complete, and then terminate the connection or
     child process.

   Transaction queues are implemented by means of a filter function.
See Filter Functions.

Network Connections
===================

   XEmacs Lisp programs can open TCP network connections to other
processes on the same machine or other machines.  A network connection
is handled by Lisp much like a subprocess, and is represented by a
process object.  However, the process you are communicating with is not
a child of the XEmacs process, so you can't kill it or send it signals.
All you can do is send and receive data.  `delete-process' closes the
connection, but does not kill the process at the other end; that
process must decide what to do about closure of the connection.

   You can distinguish process objects representing network connections
from those representing subprocesses with the `process-status'
function.  It always returns either `open' or `closed' for a network
connection, and it never returns either of those values for a real
subprocess.  See Process Information.

 - Function: open-network-stream NAME BUFFER-OR-NAME HOST SERVICE
     This function opens a TCP connection for a service to a host.  It
     returns a process object to represent the connection.

     The NAME argument specifies the name for the process object.  It
     is modified as necessary to make it unique.

     The BUFFER-OR-NAME argument is the buffer to associate with the
     connection.  Output from the connection is inserted in the buffer,
     unless you specify a filter function to handle the output.  If
     BUFFER-OR-NAME is `nil', it means that the connection is not
     associated with any buffer.

     The arguments HOST and SERVICE specify where to connect to; HOST
     is the host name or IP address (a string), and SERVICE is the name
     of a defined network service (a string) or a port number (an
     integer).

Operating System Interface
**************************

   This chapter is about starting and getting out of Emacs, access to
values in the operating system environment, and terminal input, output,
and flow control.

   See Building XEmacs, for related information.  See also
Display, for additional operating system status information
pertaining to the terminal and the screen.

Starting Up XEmacs
==================

   This section describes what XEmacs does when it is started, and how
you can customize these actions.

Summary: Sequence of Actions at Start Up
----------------------------------------

   The order of operations performed (in `startup.el') by XEmacs when
it is started up is as follows:

  1. It loads the initialization library for the window system, if you
     are using a window system.  This library's name is
     `term/WINDOWSYSTEM-win.el'.

  2. It processes the initial options.  (Some of them are handled even
     earlier than this.)

  3. It initializes the X window frame and faces, if appropriate.

  4. It runs the normal hook `before-init-hook'.

  5. It loads the library `site-start', unless the option
     `-no-site-file' was specified.  The library's file name is usually
     `site-start.el'.

  6. It loads the file `~/.emacs' unless `-q' was specified on the
     command line.  (This is not done in `-batch' mode.)  The `-u'
     option can specify the user name whose home directory should be
     used instead of `~'.

  7. It loads the library `default' unless `inhibit-default-init' is
     non-`nil'.  (This is not done in `-batch' mode or if `-q' was
     specified on the command line.)  The library's file name is
     usually `default.el'.

  8. It runs the normal hook `after-init-hook'.

  9. It sets the major mode according to `initial-major-mode', provided
     the buffer `*scratch*' is still current and still in Fundamental
     mode.

 10. It loads the terminal-specific Lisp file, if any, except when in
     batch mode or using a window system.

 11. It displays the initial echo area message, unless you have
     suppressed that with `inhibit-startup-echo-area-message'.

 12. It processes the action arguments from the command line.

 13. It runs `term-setup-hook'.

 14. It calls `frame-notice-user-settings', which modifies the
     parameters of the selected frame according to whatever the init
     files specify.

 15. It runs `window-setup-hook'.  See Terminal-Specific.

 16. It displays copyleft, nonwarranty, and basic use information,
     provided there were no remaining command line arguments (a few
     steps above) and the value of `inhibit-startup-message' is `nil'.

 - User Option: inhibit-startup-message
     This variable inhibits the initial startup messages (the
     nonwarranty, etc.).  If it is non-`nil', then the messages are not
     printed.

     This variable exists so you can set it in your personal init file,
     once you are familiar with the contents of the startup message.
     Do not set this variable in the init file of a new user, or in a
     way that affects more than one user, because that would prevent
     new users from receiving the information they are supposed to see.

 - User Option: inhibit-startup-echo-area-message
     This variable controls the display of the startup echo area
     message.  You can suppress the startup echo area message by adding
     text with this form to your `.emacs' file:

          (setq inhibit-startup-echo-area-message
                "YOUR-LOGIN-NAME")

     Simply setting `inhibit-startup-echo-area-message' to your login
     name is not sufficient to inhibit the message; Emacs explicitly
     checks whether `.emacs' contains an expression as shown above.
     Your login name must appear in the expression as a Lisp string
     constant.

     This way, you can easily inhibit the message for yourself if you
     wish, but thoughtless copying of your `.emacs' file will not
     inhibit the message for someone else.

The Init File: `.emacs'
-----------------------

   When you start XEmacs, it normally attempts to load the file
`.emacs' from your home directory.  This file, if it exists, must
contain Lisp code.  It is called your "init file".  The command line
switches `-q' and `-u' affect the use of the init file; `-q' says not
to load an init file, and `-u' says to load a specified user's init
file instead of yours.  See Entering XEmacs (emacs).

   A site may have a "default init file", which is the library named
`default.el'.  XEmacs finds the `default.el' file through the standard
search path for libraries (see How Programs Do Loading.).  The
XEmacs distribution does not come with this file; sites may provide one
for local customizations.  If the default init file exists, it is
loaded whenever you start Emacs, except in batch mode or if `-q' is
specified.  But your own personal init file, if any, is loaded first; if
it sets `inhibit-default-init' to a non-`nil' value, then XEmacs does
not subsequently load the `default.el' file.

   Another file for site-customization is `site-start.el'.  Emacs loads
this *before* the user's init file.  You can inhibit the loading of
this file with the option `-no-site-file'.

 - Variable: site-run-file
     This variable specifies the site-customization file to load before
     the user's init file.  Its normal value is `"site-start"'.

   If there is a great deal of code in your `.emacs' file, you should
move it into another file named `SOMETHING.el', byte-compile it (see
Byte Compilation.), and make your `.emacs' file load the other file
using `load' (see Loading.).

   See Init File Examples (emacs), for examples of
how to make various commonly desired customizations in your `.emacs'
file.

 - User Option: inhibit-default-init
     This variable prevents XEmacs from loading the default
     initialization library file for your session of XEmacs.  If its
     value is non-`nil', then the default library is not loaded.  The
     default value is `nil'.

 - Variable: before-init-hook
 - Variable: after-init-hook
     These two normal hooks are run just before, and just after,
     loading of the user's init file, `default.el', and/or
     `site-start.el'.

Terminal-Specific Initialization
--------------------------------

   Each terminal type can have its own Lisp library that XEmacs loads
when run on that type of terminal.  For a terminal type named TERMTYPE,
the library is called `term/TERMTYPE'.  XEmacs finds the file by
searching the `load-path' directories as it does for other files, and
trying the `.elc' and `.el' suffixes.  Normally, terminal-specific Lisp
library is located in `emacs/lisp/term', a subdirectory of the
`emacs/lisp' directory in which most XEmacs Lisp libraries are kept.

   The library's name is constructed by concatenating the value of the
variable `term-file-prefix' and the terminal type.  Normally,
`term-file-prefix' has the value `"term/"'; changing this is not
recommended.

   The usual function of a terminal-specific library is to enable
special keys to send sequences that XEmacs can recognize.  It may also
need to set or add to `function-key-map' if the Termcap entry does not
specify all the terminal's function keys.  See Terminal Input.

   When the name of the terminal type contains a hyphen, only the part
of the name before the first hyphen is significant in choosing the
library name.  Thus, terminal types `aaa-48' and `aaa-30-rv' both use
the `term/aaa' library.  If necessary, the library can evaluate
`(getenv "TERM")' to find the full name of the terminal type.

   Your `.emacs' file can prevent the loading of the terminal-specific
library by setting the variable `term-file-prefix' to `nil'.  This
feature is useful when experimenting with your own peculiar
customizations.

   You can also arrange to override some of the actions of the
terminal-specific library by setting the variable `term-setup-hook'.
This is a normal hook which XEmacs runs using `run-hooks' at the end of
XEmacs initialization, after loading both your `.emacs' file and any
terminal-specific libraries.  You can use this variable to define
initializations for terminals that do not have their own libraries.
See Hooks.

 - Variable: term-file-prefix
     If the `term-file-prefix' variable is non-`nil', XEmacs loads a
     terminal-specific initialization file as follows:

          (load (concat term-file-prefix (getenv "TERM")))

     You may set the `term-file-prefix' variable to `nil' in your
     `.emacs' file if you do not wish to load the
     terminal-initialization file.  To do this, put the following in
     your `.emacs' file: `(setq term-file-prefix nil)'.

 - Variable: term-setup-hook
     This variable is a normal hook that XEmacs runs after loading your
     `.emacs' file, the default initialization file (if any) and the
     terminal-specific Lisp file.

     You can use `term-setup-hook' to override the definitions made by a
     terminal-specific file.

 - Variable: window-setup-hook
     This variable is a normal hook which XEmacs runs after loading your
     `.emacs' file and the default initialization file (if any), after
     loading terminal-specific Lisp code, and after running the hook
     `term-setup-hook'.

Command Line Arguments
----------------------

   You can use command line arguments to request various actions when
you start XEmacs.  Since you do not need to start XEmacs more than once
per day, and will often leave your XEmacs session running longer than
that, command line arguments are hardly ever used.  As a practical
matter, it is best to avoid making the habit of using them, since this
habit would encourage you to kill and restart XEmacs unnecessarily
often.  These options exist for two reasons: to be compatible with
other editors (for invocation by other programs) and to enable shell
scripts to run specific Lisp programs.

   This section describes how Emacs processes command line arguments,
and how you can customize them.

 - Function: command-line
     This function parses the command line that XEmacs was called with,
     processes it, loads the user's `.emacs' file and displays the
     startup messages.

 - Variable: command-line-processed
     The value of this variable is `t' once the command line has been
     processed.

     If you redump XEmacs by calling `dump-emacs', you may wish to set
     this variable to `nil' first in order to cause the new dumped
     XEmacs to process its new command line arguments.

 - Variable: command-switch-alist
     The value of this variable is an alist of user-defined command-line
     options and associated handler functions.  This variable exists so
     you can add elements to it.

     A "command line option" is an argument on the command line of the
     form:

          -OPTION

     The elements of the `command-switch-alist' look like this:

          (OPTION . HANDLER-FUNCTION)

     The HANDLER-FUNCTION is called to handle OPTION and receives the
     option name as its sole argument.

     In some cases, the option is followed in the command line by an
     argument.  In these cases, the HANDLER-FUNCTION can find all the
     remaining command-line arguments in the variable
     `command-line-args-left'.  (The entire list of command-line
     arguments is in `command-line-args'.)

     The command line arguments are parsed by the `command-line-1'
     function in the `startup.el' file.  See also Command Line Switches and Arguments (emacs).

 - Variable: command-line-args
     The value of this variable is the list of command line arguments
     passed to XEmacs.

 - Variable: command-line-functions
     This variable's value is a list of functions for handling an
     unrecognized command-line argument.  Each time the next argument
     to be processed has no special meaning, the functions in this list
     are called, in order of appearance, until one of them returns a
     non-`nil' value.

     These functions are called with no arguments.  They can access the
     command-line argument under consideration through the variable
     `argi'.  The remaining arguments (not including the current one)
     are in the variable `command-line-args-left'.

     When a function recognizes and processes the argument in `argi', it
     should return a non-`nil' value to say it has dealt with that
     argument.  If it has also dealt with some of the following
     arguments, it can indicate that by deleting them from
     `command-line-args-left'.

     If all of these functions return `nil', then the argument is used
     as a file name to visit.

Getting out of XEmacs
=====================

   There are two ways to get out of XEmacs: you can kill the XEmacs job,
which exits permanently, or you can suspend it, which permits you to
reenter the XEmacs process later.  As a practical matter, you seldom
kill XEmacs--only when you are about to log out.  Suspending is much
more common.

Killing XEmacs
--------------

   Killing XEmacs means ending the execution of the XEmacs process.  The
parent process normally resumes control.  The low-level primitive for
killing XEmacs is `kill-emacs'.

 - Function: kill-emacs &optional EXIT-DATA
     This function exits the XEmacs process and kills it.

     If EXIT-DATA is an integer, then it is used as the exit status of
     the XEmacs process.  (This is useful primarily in batch operation;
     see Batch Mode.)

     If EXIT-DATA is a string, its contents are stuffed into the
     terminal input buffer so that the shell (or whatever program next
     reads input) can read them.

   All the information in the XEmacs process, aside from files that have
been saved, is lost when the XEmacs is killed.  Because killing XEmacs
inadvertently can lose a lot of work, XEmacs queries for confirmation
before actually terminating if you have buffers that need saving or
subprocesses that are running.  This is done in the function
`save-buffers-kill-emacs'.

 - Variable: kill-emacs-query-functions
     After asking the standard questions, `save-buffers-kill-emacs'
     calls the functions in the list `kill-buffer-query-functions', in
     order of appearance, with no arguments.  These functions can ask
     for additional confirmation from the user.  If any of them returns
     non-`nil', XEmacs is not killed.

 - Variable: kill-emacs-hook
     This variable is a normal hook; once `save-buffers-kill-emacs' is
     finished with all file saving and confirmation, it runs the
     functions in this hook.

Suspending XEmacs
-----------------

   "Suspending XEmacs" means stopping XEmacs temporarily and returning
control to its superior process, which is usually the shell.  This
allows you to resume editing later in the same XEmacs process, with the
same buffers, the same kill ring, the same undo history, and so on.  To
resume XEmacs, use the appropriate command in the parent shell--most
likely `fg'.

   Some operating systems do not support suspension of jobs; on these
systems, "suspension" actually creates a new shell temporarily as a
subprocess of XEmacs.  Then you would exit the shell to return to
XEmacs.

   Suspension is not useful with window systems such as X, because the
XEmacs job may not have a parent that can resume it again, and in any
case you can give input to some other job such as a shell merely by
moving to a different window.  Therefore, suspending is not allowed
when XEmacs is an X client.

 - Function: suspend-emacs STRING
     This function stops XEmacs and returns control to the superior
     process.  If and when the superior process resumes XEmacs,
     `suspend-emacs' returns `nil' to its caller in Lisp.

     If STRING is non-`nil', its characters are sent to be read as
     terminal input by XEmacs's superior shell.  The characters in
     STRING are not echoed by the superior shell; only the results
     appear.

     Before suspending, `suspend-emacs' runs the normal hook
     `suspend-hook'.  In Emacs version 18, `suspend-hook' was not a
     normal hook; its value was a single function, and if its value was
     non-`nil', then `suspend-emacs' returned immediately without
     actually suspending anything.

     After the user resumes XEmacs, `suspend-emacs' runs the normal hook
     `suspend-resume-hook'.  See Hooks.

     The next redisplay after resumption will redraw the entire screen,
     unless the variable `no-redraw-on-reenter' is non-`nil' (see
     Refresh Screen.).

     In the following example, note that `pwd' is not echoed after
     XEmacs is suspended.  But it is read and executed by the shell.

          (suspend-emacs)
               => nil

          (add-hook 'suspend-hook
                    (function (lambda ()
                                (or (y-or-n-p
                                      "Really suspend? ")
                                    (error "Suspend cancelled")))))
               => (lambda nil
                    (or (y-or-n-p "Really suspend? ")
                        (error "Suspend cancelled")))

          (add-hook 'suspend-resume-hook
                    (function (lambda () (message "Resumed!"))))
               => (lambda nil (message "Resumed!"))

          (suspend-emacs "pwd")
               => nil

          ---------- Buffer: Minibuffer ----------
          Really suspend? y
          ---------- Buffer: Minibuffer ----------

          ---------- Parent Shell ----------
          lewis@slug[23] % /user/lewis/manual
          lewis@slug[24] % fg

          ---------- Echo Area ----------
          Resumed!

 - Variable: suspend-hook
     This variable is a normal hook run before suspending.

 - Variable: suspend-resume-hook
     This variable is a normal hook run after suspending.

Operating System Environment
============================

   XEmacs provides access to variables in the operating system
environment through various functions.  These variables include the
name of the system, the user's UID, and so on.

 - Variable: system-type
     The value of this variable is a symbol indicating the type of
     operating system XEmacs is operating on.  Here is a table of the
     possible values:

    `aix-v3'
          AIX.

    `berkeley-unix'
          Berkeley BSD.

    `dgux'
          Data General DGUX operating system.

    `gnu'
          A GNU system using the GNU HURD and Mach.

    `hpux'
          Hewlett-Packard HPUX operating system.

    `irix'
          Silicon Graphics Irix system.

    `linux'
          A GNU system using the Linux kernel.

    `ms-dos'
          Microsoft MS-DOS "operating system."

    `next-mach'
          NeXT Mach-based system.

    `rtu'
          Masscomp RTU, UCB universe.

    `unisoft-unix'
          UniSoft UniPlus.

    `usg-unix-v'
          AT&T System V.

    `vax-vms'
          VAX VMS.

    `windows-nt'
          Microsoft windows NT.

    `xenix'
          SCO Xenix 386.

     We do not wish to add new symbols to make finer distinctions
     unless it is absolutely necessary!  In fact, we hope to eliminate
     some of these alternatives in the future.  We recommend using
     `system-configuration' to distinguish between different operating
     systems.

 - Variable: system-configuration
     This variable holds the three-part configuration name for the
     hardware/software configuration of your system, as a string.  The
     convenient way to test parts of this string is with `string-match'.

 - Function: system-name
     This function returns the name of the machine you are running on.
          (system-name)
               => "prep.ai.mit.edu"

   The symbol `system-name' is a variable as well as a function.  In
fact, the function returns whatever value the variable `system-name'
currently holds.  Thus, you can set the variable `system-name' in case
Emacs is confused about the name of your system.  The variable is also
useful for constructing frame titles (see Frame Titles.).

 - Variable: mail-host-address
     If this variable is non-`nil', it is used instead of `system-name'
     for purposes of generating email addresses.  For example, it is
     used when constructing the default value of `user-mail-address'.
     See User Identification.  (Since this is done when XEmacs
     starts up, the value actually used is the one saved when XEmacs
     was dumped.  See Building XEmacs.)

 - Function: getenv VAR
     This function returns the value of the environment variable VAR,
     as a string.  Within XEmacs, the environment variable values are
     kept in the Lisp variable `process-environment'.

          (getenv "USER")
               => "lewis"

          lewis@slug[10] % printenv
          PATH=.:/user/lewis/bin:/usr/bin:/usr/local/bin
          USER=lewis
          TERM=ibmapa16
          SHELL=/bin/csh
          HOME=/user/lewis

 - Command: setenv VARIABLE VALUE
     This command sets the value of the environment variable named
     VARIABLE to VALUE.  Both arguments should be strings.  This
     function works by modifying `process-environment'; binding that
     variable with `let' is also reasonable practice.

 - Variable: process-environment
     This variable is a list of strings, each describing one environment
     variable.  The functions `getenv' and `setenv' work by means of
     this variable.

          process-environment
          => ("l=/usr/stanford/lib/gnuemacs/lisp"
              "PATH=.:/user/lewis/bin:/usr/class:/nfsusr/local/bin"
              "USER=lewis"

          "TERM=ibmapa16"
              "SHELL=/bin/csh"
              "HOME=/user/lewis")

 - Variable: path-separator
     This variable holds a string which says which character separates
     directories in a search path (as found in an environment
     variable).  Its value is `":"' for Unix and GNU systems, and `";"'
     for MS-DOS and Windows NT.

 - Variable: invocation-name
     This variable holds the program name under which Emacs was
     invoked.  The value is a string, and does not include a directory
     name.

 - Variable: invocation-directory
     This variable holds the directory from which the Emacs executable
     was invoked, or perhaps `nil' if that directory cannot be
     determined.

 - Variable: installation-directory
     If non-`nil', this is a directory within which to look for the
     `lib-src' and `etc' subdirectories.  This is non-`nil' when Emacs
     can't find those directories in their standard installed
     locations, but can find them in a directory related somehow to the
     one containing the Emacs executable.

 - Function: load-average
     This function returns the current 1-minute, 5-minute and 15-minute
     load averages in a list.  The values are integers that are 100
     times the system load averages.  (The load averages indicate the
     number of processes trying to run.)

          (load-average)
               => (169 48 36)

          lewis@rocky[5] % uptime
           11:55am  up 1 day, 19:37,  3 users,
           load average: 1.69, 0.48, 0.36

 - Function: emacs-pid
     This function returns the process ID of the Emacs process.

 - Function: setprv PRIVILEGE-NAME &optional SETP GETPRV
     This function sets or resets a VMS privilege.  (It does not exist
     on Unix.)  The first arg is the privilege name, as a string.  The
     second argument, SETP, is `t' or `nil', indicating whether the
     privilege is to be turned on or off.  Its default is `nil'.  The
     function returns `t' if successful, `nil' otherwise.

     If the third argument, GETPRV, is non-`nil', `setprv' does not
     change the privilege, but returns `t' or `nil' indicating whether
     the privilege is currently enabled.

User Identification
===================

 - Variable: user-mail-address
     This holds the nominal email address of the user who is using
     Emacs.  When Emacs starts up, it computes a default value that is
     usually right, but users often set this themselves when the
     default value is not right.

 - Function: user-login-name &optional UID
     If you don't specify UID, this function returns the name under
     which the user is logged in.  If the environment variable `LOGNAME'
     is set, that value is used.  Otherwise, if the environment variable
     `USER' is set, that value is used.  Otherwise, the value is based
     on the effective UID, not the real UID.

     If you specify UID, the value is the user name that corresponds to
     UID (which should be an integer).

          (user-login-name)
               => "lewis"

 - Function: user-real-login-name
     This function returns the user name corresponding to Emacs's real
     UID.  This ignores the effective UID and ignores the environment
     variables `LOGNAME' and `USER'.

 - Function: user-full-name
     This function returns the full name of the user.

          (user-full-name)
               => "Bil Lewis"

   The symbols `user-login-name', `user-real-login-name' and
`user-full-name' are variables as well as functions.  The functions
return the same values that the variables hold.  These variables allow
you to "fake out" Emacs by telling the functions what to return.  The
variables are also useful for constructing frame titles (see Frame Titles.).

 - Function: user-real-uid
     This function returns the real UID of the user.

          (user-real-uid)
               => 19

 - Function: user-uid
     This function returns the effective UID of the user.

Time of Day
===========

   This section explains how to determine the current time and the time
zone.

 - Function: current-time-string &optional TIME-VALUE
     This function returns the current time and date as a
     humanly-readable string.  The format of the string is unvarying;
     the number of characters used for each part is always the same, so
     you can reliably use `substring' to extract pieces of it.  It is
     wise to count the characters from the beginning of the string
     rather than from the end, as additional information may be added
     at the end.

     The argument TIME-VALUE, if given, specifies a time to format
     instead of the current time.  The argument should be a list whose
     first two elements are integers.  Thus, you can use times obtained
     from `current-time' (see below) and from `file-attributes' (see
     File Attributes.).

          (current-time-string)
               => "Wed Oct 14 22:21:05 1987"

 - Function: current-time
     This function returns the system's time value as a list of three
     integers: `(HIGH LOW MICROSEC)'.  The integers HIGH and LOW
     combine to give the number of seconds since 0:00 January 1, 1970,
     which is HIGH * 2**16 + LOW.

     The third element, MICROSEC, gives the microseconds since the
     start of the current second (or 0 for systems that return time
     only on the resolution of a second).

     The first two elements can be compared with file time values such
     as you get with the function `file-attributes'.  See File Attributes.

 - Function: current-time-zone &optional TIME-VALUE
     This function returns a list describing the time zone that the
     user is in.

     The value has the form `(OFFSET NAME)'.  Here OFFSET is an integer
     giving the number of seconds ahead of UTC (east of Greenwich).  A
     negative value means west of Greenwich.  The second element, NAME
     is a string giving the name of the time zone.  Both elements
     change when daylight savings time begins or ends; if the user has
     specified a time zone that does not use a seasonal time
     adjustment, then the value is constant through time.

     If the operating system doesn't supply all the information
     necessary to compute the value, both elements of the list are
     `nil'.

     The argument TIME-VALUE, if given, specifies a time to analyze
     instead of the current time.  The argument should be a cons cell
     containing two integers, or a list whose first two elements are
     integers.  Thus, you can use times obtained from `current-time'
     (see above) and from `file-attributes' (see File Attributes.).